Almathera Ten Pack 3: CDPD 3

home *** CD-ROM | disk | FTP | other *** search

/ Almathera Ten Pack 3: CDPD 3 / Almathera Ten on Ten - Disc 3: CDPD3.iso / scope / 001-025 / scopedisk8 / a68k121 / asm68k.doc next >

Wrap

Text File | 1995-03-18 | 63KB | 1,273 lines

Page 1 wAsm68kw 68010 Macro Assembler Version 1.2.1 Docs Date: 03-Jul-87 NOTICE: THIS FILE AND THE PROGRAM IT DESCRIBES ARE COPYRIGHT © 1987, W. WESLEY HOWE. ALL RIGHTS RESERVED. A LIMITED LICENSE FOR USE AND DISTRIBUTION WITH- OUT PROFIT IS GRANTED TO POSSESSOR OF THIS FILE. NO RIGHT OF ALTERATION OF THE PROGRAM OR DOCUMENTATION IS CONVEYED WITH THIS LIMITED LICENSE. NO WARRANTY IS EXPRESSED OR IMPLIED HEREIN ON THE SUITABILITY OF THIS PROGRAM FOR ANY PURPOSE WHATSOEVER. YOU MUST RELY ON YOUR OWN JUDGEMENT AS TO WHETHER THIS PROGRAM WILL OPERATE PROPERLY WITH YOUR COMPUTER FOR WHAT- EVER PURPOSE YOU MAY DESIRE TO USE IT FOR. ADDRESS ALL QUESTIONS, COMMENTS OR CRITICISM TO: WESLEY HOWE 4800 LAKEMONT DR. RALEIGH, NC 27609 Page 2 LIMITS: Source-line length: 255 bytes (including newline) Sub-expression length: 40 bytes Parenthesis nesting: 16 levels Symbol length: 31 bytes Macro Size: 8,190 bytes Number of Macros: Available RAM Number of Symbols: Available RAM Available RAM: 1,056,768 bytes maximum heap utilized Macro Nesting: 8 levels Include Nesting: 8 levels Conditional Nesting: 16 levels Macro Parameters: 10 per invocation Sections: 255 maximum Minimum RAM necessary: 128,000 bytes Constant size: 255 bytes Storage size: 65,535 bytes Strings: 255 bytes (or line length limit) Minimum stack: 8,192 (recommended) Operating System: AmigaDOS 1.2 (CLI Only) ============================================================================== If you are an experienced 68000/68010 Assembly language programmer, you will find much of this material useful in understanding assembly language programming on the AMIGA. If you are an experienced AMIGA assembly language programmer, you may find much of the material boring, and will only want to use this as a reference document. If you don't know assembly language, then this document will not teach it, so you may need to get one of a number available reference books on MC68000 assembly language programming. In the following sections, Directives, Commands, Expressions and Mnemonics are referred to. A Directive or Command is an instruction to the assembler which causes a specific action to be performed. Some of these add data to the object file, and some only affect the way assembly operations are performed. A Mnemonic is the Pseudo-English abbreviation for an instruction the assembler is to translate into the appropriate numeric sequence and include in the object file for the MC68000 processor to perform later, when your program is run. An expression refers to any sequence of items consisting of numbers, symbols with a numerical value, and the allowable math operators all of which must reduce to a single number value. Page 3 wInvoking the Assembler:w The assembler is designed to be run only from the CLI interface. If you don't know how to find the CLI interface, read the manuals that came with the machine before trying to use this program. The minimum invocation must be the program name Asm68k followed with a source filename (separated by at least one space from the program name.) This will yield an assembly, with an object file output in the AMIGA format, and a listing file. The filenames for these files will be created by stripping any extension (period followed by characters) from the source filename and appending .o for the object filename and .lst for the listing filename. Any error messages will list to the screen. Example: Asm68k MyProgram.a Outputs: MyProgram.o (The relocatable binary object file) MyProgram.lst (A combined source and hex object file) If this isn't what you want, a wide variety of "switches" are supported to control the usage of the assembler, and the descriptions follow: (A switch is a parameter you type after the program name and source filename, with an intervening space. These switches all start with the minus sign '-' and may be followed immediately by a letter or letters as shown below.) -C This switch has been included for compatability. It should be followed with only the following characters, as many as wanted, with no spaces: S Generates a symbol table at the end of the list file (the default.) D Does nothing. C Causes Case of all Labels and symbols to be ignored. With this switch activated, LABEL, Label and label will all be interpreted as the same name. This is not the default. X Does nothing. -E Causes ERROR messages to list to the named file. It may be followed immediately with a filename containing no spaces, or type a space and then enclose the filename in double quotes if it contains spaces. You may also use the intervening space without quotes on a filename without spaces if you like. A given object filename will be used instead of the default filename normally used. -H HEADER file. Causes a search for the filename given after the switch (as above) which will be read as a source file before the source file is read (but after the initialization file, if enabled.) Just like the initialization file, if the file is not found, no warning or error is issued directly. All the source from this file will also be numbered as line 0. Page 4 -I An INCLUDE directory search path list should follow this switch and should contain directory names (no spaces allowed) separated from each other with plus signs '+', commas or spaces. If spaces are used, then you must space the list off from the switch and enclose the entire list in double quotes. Use of this switch will cause the assembler to search for an INCLUDE file in each of the named directories if it is not found in the current one. -L Causes the LISTING file to be generated (also a default.) The usage is just like the -O switch. -N This switch turns things off (NO.) Like -C, you should follow it with a series of letters from the following list, without any spaces: S Turns off the SYMBOL table normally produced at the end of the listing file. L Stops the LISTING file from being generated. E Inhibits the ERROR file, if you turned it on. V A synonym for the E switch above. P Inhibits the PAGINATION of the listing file. O Inhibits the OBJECT file generation. Q Inhibits the conversion of mnemonics to QUICK form. The default is to convert allowable values of ADD and SUB to the quick form if it is safe (values already defined.) X Keeps the assembler from stripping the eXtension from the source filename when forming default filenames. R Causes the assembler to generate the object code in a non- RELATIVE format. The format used is the Intel format, and the program counter is only output to 16-bits of significance. No symbol or relocation information is output, and no linker or loader is available to operate on this format. -O Causes the OBJECT file to be generated (this is a default value.) On this switch, if no filename is given, a default filename will be formed like the error and listing names, using the extension .o -R This is the relax switch. The following parameters should follow the switch immediately, with no spaces: M Stops the assembler from reporting that less parameters were supplied for a macro than were called. R Eliminates messages about relative references to other sections. Note that any mnemonic that has a PC-relative mode available will still assemble as PC-relative, and will not run on the Amiga. Declare all references between sections as ENTRY (XDEF). The linker can be used so as not to include resolved references in the load file. -V VERIFICATION file. Another name for the -E switch. -X This switch should be followed immediately with up to 6 characters, and will cause the default object filename to be formed by stripping the extension and appending a period and the characters following the X. > The right bracket, followed immediately with a filename, will cause the signon, progress and all error messages to be diverted by AmigaDOS to the named file when it is the first parameter after the program name. If it is not the first, the assembler will send the error messages to the named file. Page 5 All the preceding switches may be used in either UPPER or lower case, and will generate the same results. The source filename should be the first parameter after the program name, but only to avoid confusion. It must be the only parameter not associated with a switch, and may not be given twice. The source filename is the only mandantory command-line parameter. Page 6 Math & Logic Operators: + Addition - Subtraction or Negation ~ NOT << Left shift >> Right shift & AND | OR ! OR (for compatability) ^ XOR (Exclusive OR) / Integer Division %% Integer Modulo * Integer Multiplication or Program Counter Location All expressions evaluate in strict Left-to-Right order, as divided by parentheses. Symbols and constants may be mixed, and space or tab characters may be included. No individual portion of the expression may exceed 40 characters (NOTE: a 'portion' would be any symbol or number alone.) Some examples: 4+(7*2) Yields 18 4 + ( 7 * 2 ) Yields 18 4+7*2 Yields 22 -4*6 Yields -24 6*-4 Yields -24 4(6*7) Error ('A'+1) Yields 66 "A" + 1 Yields 194 'ASDF'+0 Yields 1,095,976,006 Program Counter: The symbol * can be used as shorthand for the current PC (relative offset) under the following criteria if it occupies the position in an expression normally occupied by a value. Page 7 Numbers and Constants: Binary: A binary number is either [1] prefixed with the '%' (percent) character, or [2] followed immediately with the letter 'B' (UPPER or lower case). It may contain only the digits '1' or '0'. Octal: An octal number is either [1] prefixed with the '@' (at) character, or [2] followed immediately with either the letter 'O' or the letter 'Q', in either case. Only the digits '0' through '7' are valid. Decimal: A decimal number contains only the digits '0' through '9', and may be optionally followed immediately with the letter 'D' (either case.) Hexa-Decimal: HexaDecimal numbers contain the digits '0' through '9', and the letters 'A' through 'F' (in either UPPER or lower case.) They may be [1] prefixed with the '$' (Dollar) character, or [2] they must start with a digit and be followed immediately with either the letter 'H' or the letter 'X', in either UPPER or lower case. A leading '0' may be prefixed for the post-fix form. Leading zeros do not affect the value of any of the number forms, although the 40 character limit applies to them also. Characters: Multiple ascii character may be included by enclosing them in QUOTES. The single quote will yield an ascii value, and the double quote will yield an ascii value with bit 7 SET (or'd with 128). Multiple byte constants are evaluated by successive left-shifts. Only the last 4 characters are retained as a 32-bit value. Some Examples: The number 1,000 (one thousand) may be represented any one of the following ways: 1111101000B 01111101000b %1111101000 1750Q 01750o @1750 1000D 0001000d 1000 3e8H 03E8h $3e8 'E0'-'AH' Page 8 Assembly Line Format: An input assembly line follows the following models: Label1 Mnemonic Operand , MoreOperands ;comment Label2: Mnemonic Operand Mnemonic Operand Label3: Mnemonic LabelOnly * a comment only ; another comment Note that the LABEL either starts in the first column, or is followed by a colon. The Mnemonic field is separated by at least one space or tab, and never starts in the first column. Operands, where needed, follow, separated from the Mnemonic by at least one space or tab. Multiple operands are separated from each other by a comma (the comma flags the assembler that there is another operand available.) An asterisk in the first position on the line indicates a comment only line, or comments may follow complete operands with a semicolon separator. Assembler directives occupy the Mnemonic position, and comments are optional. Labels are allowed on all lines, and are required for some assembler directives. Page 9 Constants: The following Assembler directives cause the inclusion of data in the Object file: DB Yields 8-bit values. Either STRINGS, Symbols, Labels, numbers or expressions may be evaluated. Multiple operands need to be separated by commas, and generate successive bytes up to a limit of 255 bytes (the line- length limit should prevent this from ever being reached.) DW Yields 16-bit values, in Hi-Lo order. The format is the same as the DB directive, except STRINGS will not be evaluated. If the address is not a word address, a pad byte will be appended to the previous line, and a non- fatal error message will be issued. DL Yields 32-Bit values. Otherwise equivalent to DW. DC This directive is the same as DW. Appending .L or .B (in either case) will change the function to be the same as DL or DB, respectively. (DC.W is legal.) ASCII This command yields a sequence of bytes equivalent to the ascii value of the operands (delimited by quotes) provided. Single quotes will yield the normal value, and double quotes will yield values with bit 7 SET. Within the delimited STRING, a '\' (backslash) character, followed by up to three decimal digits will cause inclusion of a byte with the same numerical value, or if followed by any other character will allow the inclusion of that character immediately following. (This is useful for including quotes and backslashes in the string.) Quotes may also be included by following the convention of using two quotes in succession.A limit of 255 values applies. CSTRING This command is the same as ASCII, except an additional byte with the value 0 is appended (as in the C language.) PSTRING This is the same as ASCII also, except a leading byte with a value equal to the number of bytes following is prepended (as used in the PASCAL language). ISTRING This variant of ASCII will cause the final character to have its most significant bit of the opposite (INVERTED) value from the rest of the characters in the string (as defined by the delimiting quotes). This form is popular among 8-bit machines, and some BASIC interpreters. It's usefulness with the new international 8-bit standard ASCII is questionable, but it may be helpful, so it has been included anyway. DCB This command accepts the .B .W and .L size specifiers (or defaults to WORD.) It generates as many values as the operand expression evaluates to (up to 255 bytes total), of the size specified. WORD and LONG sizes are forced to an even address alignment. Page 10 Symbol and Labels: A Label is an address designator. It is placed before a mnemonic or a data location, and acquires a value equal to the relative program counter value at that location. A standard Label may only be defined this way once in a program, but may be referenced as many times as needed. It must start with a letter, a period or the '_' (underscore) character, and may contain only these characters, or the digits '0' through '9', without spaces up to a total of 31 characters. When you define a label, it must appear as the very first item on a line, or you must append a ':' (colon) character to it. (You may have the colon in the first case also.) You must not use the colon on the label other than when you define it, or you may get an erroneous interpretation of your expression. A Symbol starts off looking like a label, and follows the same rules, except the following commands modify it to acquire a new type and value: EQUATE Sets a permanent, absolute value equal to the value of the expression following this directive. STRING values are not allowed. SETVAL Sets an absolute value which is retained until a new value is set. You may not later use EQUATE on this label, but you can EQUATE a different label to the set value. EQUR Gives a value to the symbol which may later be used in place of a standard data or address register. This is valid only for D0-D7 or A0-A7 (SP is a synonym for A7). You cannot use this value other than to reference a register in a MC68010 mnemonic. REG Accepts a register-list operand for use with the MOVEM mnemonic. A register-list looks like this: A2-A7/D1/D3-D7 Which defines the registers A2 through A7, D1 and D3 through D7. In fact, all the registers except A0, A1, D0 and D2. Only the standard address and data registers may be defined in this fashion. MACRO Assigns a sequence of input lines, with replacable parameters, which will later be substituted for any line which uses this symbol as a mnemonic or command. More on Macros later. These Directives must have a Label in the Label Field for assignment, except for MACRO, which may have its name in the operand slot. Page 11 You must avoid referencing a symbol before giving it a value, or the assembler will complain (sometimes), because the forward reference will make it type the symbol as a label, which is an address, not a number. Labels, of course, may be referenced before use, and its value will be substituted on the second pass. In fact, this is the only reason you need a two-pass assembler. Local (Numeric) Labels: A line may be labeled with a special Local Label which attaches itself to a specific offset from the last proper line label, as previously described. A Local Label is a sequence of up to three decimal digits followed by the '$' (Dollar) character. Like a regular Label, if it does not start at the beginning of the line, it must be followed by a colon. A Local Label may be referenced in an operand anywhere a line Label would, but its scope is only between one regular Label and the next. Each time a new regular Label is used, the Local Label may then be redefined and reused with a different value. An example: Start Jsr Initialize_Data 001$ Jsr Initialize_Serial Move.b D1,ChangeFlag Cmp.b #0ffh,D1 Bne 1$ Note that 001$ and 1$ will evaluate to the same location. You need not start with one and may use any numbers you desire, as long as their value does not exceed 999. Also, note that $1 and 1$ are interpreted differently; the first is an absolute expression, and the second is a relative address. Local Labels may not be used for Macro names, although they may be used within Macros, and cannot be used to represent Numbers, EXTERNal or ENTRY types. Page 12 Conditional Assembly Directives: The following Commands allow assembly to proceed until a matching ENDIF Directive is found, or disable assembly until the ENDIF is reached if the condition is not met: IFEQ Expression EQuals zero. (e.g. 4-4) IFGE Expression Greater than or Equal to zero. (e.g. 4-4 or 4-3) IFGT Expression Greater Than zero. (e.g. 4-3) IFLE Expression Less than or Equal to zero. (e.g. 4-4 or 4-5) IFLT Expression Less Than zero. (e.g. 4-5) IFNE Expression is Not Equal to zero. (e.g. 4-5 or 4-3) The above conditionals are evaluated to 32 bits, but the condition decision is based on their WORD (16-bit) value. IFD Label following was already Defined (not just referenced.) IFND Label following has Not yet been Defined. IFC Both STRINGS following Compare (same length and characters.) IFNC Both STRINGS do Not Compare (different length or characters.) The last two conditional commands need two operands, separated by a comma. They may be delimited with Quotes (single or double), or by a left bracket '<' and right bracket '>' pair, or the first string will start at the first character which is not a space or a tab, and end at the first occurrence of a comma or space or tab, and the second will start at the next character which is not a comma or a space or a tab and will end at the first space, tab, semicolon or newline character. To enclose spaces in the string, you must use either the quote or bracket delimiters. To enclose quotes, use the brackets, and to enclose brackets, use the quotes. Both quotes and brackets cannot be passed together unless you use the spaces, but then you can't have spaces in the string. Just shows to go you, everything is a compromise. Any backslash character sequences are not expanded before comparison (except inside Macros.) Each Conditional command DO level ends with an ENDIF command. DO levels nest only to 16 levels, or a fatal error will be generated (whether the assembly is on or off, each IFxx increases the level count, and each ENDIF decreases the count; exceeding 16 or going below zero are fatal errors.) DO levels are not active during a macro definition, but will be evaluated during a macro expansion. Page 13 Other Assembler Directives: RESERVE Creates an uninitialized data storage area, with a size equal to the expression following it. The size designators .B .W and .L (any case) may be used, or WORD is assumed. The expression following the Directive is expanded to the size specifier. This is the only Directive which is not limited in size to 255 bytes for the result, but may yield up to 65,535 bytes. ENDSRC Shuts off assembly for the current DO level. (See the section on conditional assembly for DO level explanation.) If you are not in a DO level, the source is read to the end of file, but no assembly action will occur. OPTION This command accepts the following operands only: M - Allows macro call lines to print in the assembly listing. (If List is on.) This is the default condition. NM - Hides macro call lines, showing expansion lines only. L - Turns on listing. (The default condition). NL - Shuts off Listing. (Neither of these commands override the command-line switches directly, they only control the flow of data. An assembly will still create a list file if not prohibited, Option NL will just make it an empty file. If the list file was disabled on the command line, Option L will not send the listing anywhere. None of the operands are case-sensitive.) TITLE Accepts a STRING (delimited by quotes) which will label all pages, if paging is not disabled. The Maximum title length is 40 characters. Also cause pages to be numbered. ORIGIN Sets the program counter to the value of the expression following the command. Origin remains relative on AMIGA output format. PAGEUP Causes a page to end if paging is not disabled. A form-feed character is sent, and a page heading with the optional title (see TITLE) is printed. Page 14 SECTION This command causes a new section, or Hunk, to be created in the AMIGA output format. The first operand must be a name containing no spaces and having less than 40 total characters. The second operand, if given, should be separated by a comma and should be either CODE, TEXT, DATA or BSS. If none is given, CODE is assumed. (only the first character is checked, however, so DUMMY will yield a DATA section definition.) TEXT is equivalent to CODE. Case is not significant on the section type, but case is important for the name. Optionally, the type may be followed by a comma and either PUBLIC, FAST or CHIP to specify the memory type in which the hunk is to load. If the operand isn't present, PUBLIC (any) is the de- fault. If the section name has been used before, assembly will proceed at the next location as was previously defined, and the resultant code, data or storage space will be coalesced into one Hunk. AmigaDOS loads different hunks into different memory locations, so all references to data between sections should be to Labels declared as ENTRY (XDEF) to ensure assembly as absolute locations. A warning is issued (unless shut off, see the switches section) when this condition is detected. See the AmigaDOS manual for more information on Hunks. IDENTIFY This command should be followed with a name, which will be given to the program unit (a program unit is a hunk or a collection of hunks to be fed to the linker.) Only the first name given will be used, subsequent uses are ignored. If the IDENTIFY command is not used during an assembly, the object file will be given a name that has 0 characters in it. (Null string.) EXTERN Followed by one or more Labels or symbols (separated by commas.) These labels must not be defined within the entire assembly source, and cause the assembler to generate the appropriate external reference instructions in the object file (AMIGA format only) for resolution by the linker. Multiple EXTERN usage on the same Symbol name is ignored. ENTRY Followed by one or more Labels or Symbols. These labels, which need to be defined somewhere, allow locations within the program unit to be visible to the linker to resolve other program unit EXTERNal references. A program that consists of more than one object file will need to have an ENTRY in one unit for every EXTERN in the other units, or the program will 'BOMB' and probably either lock-up the machine or cause the dreaded GURU to appear. References between different sections must be to ENTRY labels, since the AMIGA loader will place each section wherever it will fit, and resolve all these different addresses. If you never use the section command, the entire program will have to fit in the same place, and might not be able to be loaded if there is not a spot big enough for the whole thing (depending on how many tasks might also be running, etc.) As for EXTERN, duplicate references to the same name cause the second reference to be ignored. Page 15 EXECUTE This command will pass the quote delimited string following it to AmigaDOS during the second pass. The current window is the input and output. A more detailed description of the Execute routine is located in the AmigaDOS manual, but basically the same things you can do from the CLI may be contained within the string and executed from within the assembler. The Source, Object and any open Include files will be locked, and cannot be accessed at this time. No use is made of the return value from the program called. CNOP This Directive causes null filler bytes to be inserted into the object file until the desired alignment is reached. There may be one or two values after the Directive, separated a comma. The second value given, or the single value is the desired alignment value you want, and the first value when two values are given is how many more bytes to add beyond this point. There may not be more than 255 bytes generated in total to acheive the desired alignment, and no restrictions are imposed on what alignment values can be used, but values that are not powers of two will normally not generate a correct alignment. If you want to set the Program Counter 2 bytes beyond the next PC location evenly divisible by 8 use the command like this: CNOP 2,8 The predominant reason for using this command would be to align data at specific offsets, and to create data structures in specific formats. Page 16 Include Files: Up to 8 levels of include files may be inserted into the assembly with the INCLUDE Directive. The syntax demands a Filename or Path, delimited by quotes. Include file directory searches are supported by command-line parameters (Detailed in another section.) Include files may be called by Macros, and Macros may be used by Include files, up to their respective nesting levels (8 each.) The INCLUDE directive will cause the next source line to be read from the named file as if the entire contents appeared in the original source file, except line numbering will start at one again, and the line number will be followed by a '+' (plus) sign. When the end of the Include file is reached, the line number will revert to the one following the line which invoked the INCLUDE Command. Special provisions have been made to allow automatic and command-line inclusion of header and/or macro definition files before assembly starts, and these files do not count in the nesting level limits for Include files. A later section will describe command-line parameters and the configuration file. A SPECIAL NOTE: Several of the existing include files from Commodore do not assemble correctly (particularly those in the exec directory.) Many of the source lines in these files contain comments which are delimited only by spaces and an asterisk. Asm68k is not restrictive about spaces within an expression, and tries to assemble the asterisk as a multiplication operator with the words in the comment being looked at as labels, and gives appropriate error messages. Make sure the comments are stripped or delimited by a semi-colon. A few of the files contain Macro error checks using an IFC \1,'' which will not assemble correctly with Asm68k. Use IFEQ NARG instead. Lists.i contains a parenthesized expression as an offset for an address register. Asm68k will not accept parentheses within 68010 mnemonics except when they are immediate type, as the parentheses denote a register designation. These changes will make both assemblers happy, and the include files more portable between applications. Page 17 Macros: The best feature of the assembler, and the hardest one to master, is the use of the MACRO command. A Macro is simply a sequence of source lines which may be saved and inserted as often as wanted just by using the name you gave it as a command. A Macro may contain any of the other Directives and Mnemonics the assembler recognizes except another MACRO definition command, although you may use the name of a defined Macro in your Macro (up to 8 levels deep.) A Macro is defined (and it must be before being used) by placing the MACRO in the Mnemonic Field, either before or after its name. The name for the Macro must follow the rules for Labels if it is on the left side, or if it is on the right side it needs to be separated by at least one space or tab from the MACRO Directive, and follow all the Label rules except it does not need to be followed by a colon. All the subsequent lines up to the one which contains the ENDMAC command will be saved for subsequent use. The real power of Macros comes from their use with replacable parameters. When you issue a Macro name as a Command, up to ten parameters (numbered from one to nine, with zero for ten) may be included in a comma, space or bracket separated list after the name for use within the Macro text. To make these parameters appear in the Macro expansion, place a '\' (backslash) character followed immediately (no spaces) with the digit of the parameter you want in the definition. When the macro is expanded, the text will include the parameter placed on the calling line, and will be evaluated just as if the source had included it as it appears. Parameters are gathered and passed as they appear, quotes and all. The backslash character may be passed to the Macro by including two backslashes in the calling line, and any non-numeric character following a backslash other than a backslash will pass both the backslash and the character following it to the Macro. To pass numeric sequences for use in a string (such as with the ASCII directive), use two backslashes [as in \\13, to put the sequence \13 , which puts a carriage return with the quoted string]. Conditional Directives are effective within the Macro, under the same rules as they follow elsewhere. If assembly is enabled, and the Directive MEXIT is encountered, expansion of the Macro is suspended, and the next source line will be the one following the Macro invocation line, after the assembler has examined the remaining Macro text and resolved all the IFxx and ENDIF levels. To make Macros respond differently with different numbers of passed para- meters, the special symbol NARG (not case-sensitive) has been reserved. It will yield a value equal to the number of parameters found on the invocation line within a Macro expansion, and zero elsewhere. Page 18 One additional feature within Macros is the \@ (backslash followed by the at character). While the Macro is being expanded, this combination is changed to a period followed by three decimal digits. These digits increment starting from zero every time a macro call is made that uses the \@ combination, and will be used for the duration of that macro (a contained macro call will use a new number, then when it ends the former macro's number will be used until it ends. This allows unique symbol names to be generated within the Macro text, allowing branch instructions to occur. Local (numeric) Labels are effective within the Macro, but they do not attach to the Macro name, nor are they canceled by the Macro invocation (unless the invocation line was labeled.) Page 19 Do Nothing Directives: The following directives are accepted by the assembler, but cause no action and generate no code, just as if they were comments. They have been included to allow use of source code written for other assemblers. MASK2 FORMAT SPC NOL OFFSET Synonym Directives: The directives in the left column are substitute names for the directives in the right column, and were included for source compatability: DS RESERVE END ENDSRC EQU EQUATE SET SETVAL TTL TITLE ENDC ENDIF ENDM ENDMAC RORG ORIGIN XREF EXTERN XDEF ENTRY RORIGIN ORIGIN =============================================================================== Unimplemented Directives: The following Directives, found in some other assemblers, have not been implemented in this version: IDNT FAIL LIST LLEN PAGE PLEN NOOBJ NOLIST NOPAGE INCDIR A startup Macro file has been included with this package to allow some compatability if these are needed. Page 20 Startup Configuration: If a file named Asm68k.cnf (or a filename the same as the assembler with the extension .cnf) is found in the same directory spec the assembler was called from, it is read and acted on. The current version looks for 3 items in this file, the pagelength (which must be greater than 11), the name (and path) of the startup file and the assembler startup defaults. The format is: Page Length: 1 byte (11-255), binary = 66 File Path: up to 31 bytes, ascii = Asm68k.mac Name Terminator: 1 byte, binary, value 0 = MANDANTORY Output Object File: 1 byte, boolean, Y or N = Y Output Listing File: 1 byte, boolean, Y or N = Y Output Error File: 1 byte, boolean, Y or N = N Object as Intel Format: 1 byte, boolean, Y or N = N Quick Conversion allowed: 1 byte, boolean, Y or N = Y Symbol Table Output On: 1 byte, boolean, Y or N = Y List Paging Enabled: 1 byte, boolean, Y or N = Y Relax Relative Error check: 1 byte, boolean, Y or N = N Relax Macro Parameter count: 1 byte, boolean, Y or N = N Remove extension from source: 1 byte, boolean, Y or N = Y Show Macro call lines: 1 byte, boolean, Y or N = Y Any characters after these are ignored. When assembly begins, if this file is found, it is read and assembled as if it was the beginning of the Source file. All lines from this file are numbered 0, and no warning occurs if the file is not found (unless you were depending on the definitions in your program, then you would have lots of error messages.) Beware when making this file that the null character MUST be at the end of the pathname. You can create a file from the keyboard using the command: COPY con: to Asm68k.cnf then typing a character for the pagelength (B is 66, the default), followed with the pathname for the startup file, followed with control@ (CTRL key and 2 key together), followed with the sequence YYNNYYYNNYY (these duplicate the defaults) and then ending it with a control\ (CTRL and \ keys together.) If you make a mistake, you cannot edit the file, so do the control\ and start over. Case is not significant on the boolean values, and, except for BASEREG value (an address register number), only 'Y' is actually checked for. When the assembler runs out of characters or has read enough, it quits the input read. No error messages are issued for bogus values, so be careful when creating this file. If you have it available, a better approach would be to use Newzap on the file distributed with the assembler. If you want to set different defaults, but don't want a startup file read, make the file- name NIL:. In all cases the standard defaults can be over-ridden by command-line switches, which are examined AFTER this file is read. Page 21 Other notes on use: Case is normally significant on Symbols, Labels and Macro names unless the -CC switch is used. The Directives, Mnemonics and special symbols will be recognized in any mixture of UPPER and lower case. The only truly reserved symbols are the following: NARG MACRO ENDMAC ENDM A0 A1 A2 A3 A4 A5 A6 A7 D0 D1 D2 D3 D4 D5 D6 D7 SP CCR USP SR PC All the other special Symbols, Mnemonics and Directive names may be defined and used as Labels, or may be implemented as Macros, but be careful when doing this to avoid circular references, which will not be detected until the Macro nesting level is exceeded, or a write error results from the disk being full. For example, if you redefine JSR as a Macro, and want to use it in the Macro definition, don't call the assembler with the -CC switch, and be sure to use a different case within the Macro text to get the assembler to recog- nize the Mnemonic, which is case-insensitive, from the Macro name. This allows the maximum flexibility for the assembler, with only a minimum of care from the programmer. Page 22 Error Messages: The assembler uses as much logic as possible to generate a line of code in spite of erroneous input. If a reliable evaluation can be made, a source line will be interpreted regardless of errors, however some of these lines may not be what you meant. Even the little bit of DWIM in this assembler occupies a lot of code space. Because assembly of erroneous lines is attempted where possible, you may find multiple error messages referring to the same line. The listing file will only contain the first error detected, however the screen list or error file will also list the errors in the order they were detected. Some errors may generate errors later, especially if typing errors cause the assembler to find an item it thinks is an undefined symbol in an expression, and you later used this symbol for another purpose. The following is a list of error messages, and explanations: 1: Error in Expression Value The expression being evaluated contained some garbage. 2: Duplicate Line Label An attempt at defining a Label twice was detected. This error does not apply to ENTRY and EXTERN label types. 3: Undefined Label in Expression The symbol or label used in the expression was not defined anywhere in the source file. 4: Syntax Error The assembler could make no sense of what you were trying to tell it to do. 5: Operand Too Large The operand was greater than the value allowed for the operation being performed. 6: Invalid Register Specified The register called for in the current operation and what was found are not compatable. 7: Undefined Mnemonic or Command An item in the Mnemonic field is not a defined Macro or valid mnemonic or directive. May also be caused by using a label outside of column one without a colon following it. 8: Improper use of Unary Operator A Unary operator ('-' or '~') was found right after another math operator. The expression evaluator cannot handle this, so it is ignored and this message is output. 9: Division by Zero A Division or Modulo operation was attempted where the right hand value was zero or undefined. The result of this operation is set to zero. Page 23 10: Too Many Right Parentheses More right parentheses were found than left parentheses. 11: Missing Right Parenthesis More left parentheses were used than right parentheses. 12: Too Many Parenthesis Levels More than 16 levels of parentheses were attempted to be opened. 13: Invalid Character in Expression A character was found in the expression that is not any of the defined mathops, numbers, symbol characters or newline characters. 14: Closing Quote Absent No closing quote on a character constant was found. 15: Operand Field Missing An operand was needed, and was not there. 16: Bit Operand Required The expression needs a bit operand, and what was found was not of the required type. 17: Invalid Bit Specified The data found cannot be used legally to specify a bit. 18: Immediate (#) Operand Needed The data given was not preceded by the '#' (pound) sign, and needed to be. 19: Branch or Jump Out-of-Range The address evaluated is outside of the range allowable for the branch of jump mnemonic specified. ** Command Line Required ** The message output when no arguments are present on the command-line (you need at least the source filename.) Also a Fatal error. ** Unrecognized Switch ** A switch or a character within a switch was not one of the valid switches. Not a Fatal error. ** File Write Error ** An error occurred during a file write, as reported from AmigaDOS. May be caused by a full disk. ** Source Filename Missing ** The source filename was not present, corrupt or was given twice. A Fatal error. ** Parameter Too Long ** An Item on the command-line was too long to be evaluated. Also Fatal. Page 24 ** Insufficient Free Memory ** This error occurs when the memory pool does not contain enough memory in a size large enough for the request from the assembler to be filled. Execution stops immediately. ** Too many Include Files ** This error occurs when you try to open the ninth Include file before closing one. ** Couldn't open Source file ** AmigaDOS did not return information indicating that the source file was ready to be read from (or it isn't there.) No assembly will take place without a source file. ** Couldn't open Object file ** A Dos error occurred trying to open the object file. ** Couldn't open Listing file ** Same error from listing file open attempt. ** Couldn't open Error file ** Like above, but on error file attempt. 33: ENDMAC Command missing The end of the source file was reached, and the assembler was still saving a macro definition. 34: Too Many Parameters present More parameters than the assembler has space to store were found. 35: Parameter Too Long An item in an expression or an operand was longer than the defined limit. 36: Closing Quote Missing A string definition should be bounded on both ends with matching quotes. 37: No Label on Line No label was present for the Directive to act upon. 38: Macro called using Symbol label A symbol name found in the mnemonic field was attempted to be used as a Macro, and was found to be a Label. ** Too many nested Macros ** This Fatal error occurs when the ninth Macro call is issued before any of the previous Macro calls have ended. 40: Macro redefinition Error The name used with the MACRO command is already the name of a previously defined Macro. Page 25 41: ENDMAC command without MACRO definition You didn't use the MACRO command to define your Macro, or you issued the ENDMAC command twice. If you are attempting to get two or more exit points from a macro, use the MEXIT Directive. ** INCLUDE file unable to be opened ** This Error occurs when the filename associated with the INCLUDE command was not found after the include directory list was exhausted. ** Source or Include file line too long ** An input line read from disk contained more than 255 characters in a row without a carriage return or linefeed. 44: Not enough Macro parameters supplied An expansion was attempted and there were not enough parameters on the Macro call line. This may be relaxed with a command-line switch. 45: Label Value changed between passes This unusual error occurs when the value of a Line Label is different on the second pass than it was on the first pass. The whole assembly file is probably corrupt, and it is likely that the message will repeat with every subsequent Line Label found. Forward references and absolute references to SETVAL Labels, or conditional compilation based on SETVAL Labels are the likely culprits behind this error. 46: Invalid Label - Forward Referenced A Label which was referenced before it was used was later found in a context other than usage as a relative location. 47: Local Definition of External Symbol not allowed If you declared a Symbol to be EXTERNal, you cannot define it within the current assembly. Use the ENTRY Directive instead if this is what you want. 48: Unavailable Addressing Mode Used The addressing mode used for the Mnemonic on this line is not one which is allowable for that Mnemonic. 49: Invalid Item in External Reference Expression An external reference included an item which did not belong there. This also occurs on an attempt to generate PC relative references to external addresses. ** Too Many Section Definitions (Limit = 255) ** The message is self-explanatory. Page 26 51: Invalid Section Type - Section CODE used An item found after the section name was not one of the valid section types - CODE, TEXT, DATA or BSS; or the mem- ory specified is not one of the valid types PUBLIC, CHIP or FAST. The type is set to CODE,PUBLIC. 52: Alignment Error - Pad Byte Added All the 68010 Mnemonics and WORD and LONG oriented Direct- ives need to be aligned on an even address. The Assembler attempts to correct this by adding a null byte to the previous instruction, and adjusts the Program Counter and Label values accordingly. ** Too Many Conditional Levels Attempted The seventeenth conditional Directive was found before an ENDIF Directive was. ** Conditional End without Conditional Statement There are more ENDIF commands than matching conditional Directives. 55: Relative Reference Outside of Current Section An attempt to use a PC relative mode to a Line Label that was not declared as an ENTRY label was attempted. Also occurs on Data references to other sections without using the ENTRY type-definition. This message may be suppressed with a command-line switch. 56: Code not allowed in Data & Bss Sections DATA sections may contain only initialized and uninitialized data locations, and BSS sections may contain only un- initialized (RESERVE) data. 57: Redefinition of an Equate not Allowed You cannot change the a Label value that has been EQUATEd. 58: Equate to previously SET Label Disallowed A Label that was set cannot later be upgraded to an equate in the same assembly. The assembler handles decisions on equated labels, whose value cannot change, differently than set labels, whose value may be redefined. Since the length of 68010 instructions vary with the address mode, a set label is always treated as a LONG value (unless otherwise specified) and an equated label is treated for the value it contains. Since the assembler always attempts to use the shortest instruction length possible, a change in the type of a label can cause bad code to be generated. Page 27 Addressing Modes: The following models show the valid address modes for the 68010 processor as they are recognized by the assembler: ( 'n' represents a digit from 0 to 7, X represents either 'D' or 'A' for an address mode 'ALabel' represents a symbol with an absolute or an external value, 'RLabel' represents a Line Label or an ENTRY typed label, 'number' refers to an actual numerical value, and the other items are what they are. Case is not significant except on Label and Symbol Names. Defined REG Labels of the proper type may be used in place of the register names.) IMMEDIATE: #number #ALabel DATA REGISTER DIRECT: Dn ADDRESS REGISTER DIRECT: An SP ADDRESS REGISTER INDIRECT: (An) (SP) ADDRESS REGISTER INDIRECT WITH POST INCREMENT: (An)+ (SP)+ ADDRESS REGISTER INDIRECT WITH PREDECREMENT: -(An) -(SP) ADDRESS REGISTER INDIRECT WITH DISPLACEMENT: number(An) number(SP) ALabel(An) ALabel(SP) ADDRESS REGISTER INDIRECT WITH DISPLACEMENT AND INDEX: number(An,Xn) Alabel(An, Xn) number(SP, Xn) ALabel(SP,Xn) PROGRAM COUNTER RELATIVE WITH DISPLACEMENT: RLabel RLabel(PC) number(PC) PROGRAM COUNTER RELATIVE WITH DISPLACEMENT AND INDEX: RLabel(Xn) RLabel(PC, Xn) number(PC, Xn) SHORT ABSOLUTE: ALabel number (where the value is less than $007FFF or greater than $FF8000) LONG ABSOLUTE: RLabel (to another section) ALabel number (where the value doesn't qualify for short mode) SPECIAL: USP CCR SR VBR SFC DFC Page 28 16-bit relocatable data Base Register Addressing Support has been included for Base-Register addressing of data sections for use with the "smalldata" option of the BLINK linker. When the BASEREG directive is used in the source file with the operand 'BLINK', references to external labels using "address register indirect with displacement" addressing are output as ext_dref16, which BLINK will adjust so that the offset represents the location within the merged data hunk where the referenced data is located. If you are using the Lattice startup module, and linking your code with BLINK, register A6 is supported for this use. If you are designing your own startup module, you need to set the base register you've chosen to the start of the data hunk(s). Additionally, the command "BASEREG [register]" will convert all references to external labels, except for immediate addressing mode and the JMP and JSR mnemonics, to "address register indirect with displacement" using the specified register. Using the command "BASEREG OFF" will end the automatic conversion. This feature has been included to allow easier use of this mode, both in new designs and in converting existing programs. Compatibility with other assemblers is also enhanced by using this mode, since other assemblers which do not support this function may still assemble the file if BASEREG is defined as a macro with a null effect (such as DS.W 0). Using this mode will save 2 bytes per instruction (or 4 bytes if both the source and destination reference external data). Object modules assembled with either of these options will not function with the standard Amiga linker ALINK; you MUST use BLINK to take advantage of these features. Using BASEREG will cause all references to EXTERNal Labels where "address register indirect with displacement" mode was used to be output as relative to the data module, until the "BASEREG OFF" directive is encountered. If the data section(s) are in the same source file, conversion will not be automatic with the BASEREG command, as conversion is triggered by the Label's prior definition with the EXTERN (XREF) directive. In order to use PC-Relative data references, such as those used on open library calls such as _LVO(An) , use the "BASEREG OFF" command, and reset the Base-Register afterwards. Page 29 Release History: Version 1.0.1 Alpha1.........released 02-Jan-87. Version 1.0.1 Beta1..........released 11-Jan-87. Version 1.0.1 Beta2..........released 20-Jan-87. Version 1.0.1................released 28-Feb-87. Version 1.0.2................released 14-Apr-87. Version 1.0.3................released 24-Apr-87. Version 1.1.0................released 21-Jun-87. Version 1.2.0................released 28-Jun-87. Version 1.2.1 Beta1..........released 03-Jul-87 1) CMP and CMPI mnemonics with immediate operands less than 8 once again assemble (broken in 1.2.0) 2) Forward referenced labels no longer show as un- referenced on symbol-table dump. 3) Insidious error on expressions referencing other sections and using both Line labels and either EQUated or SET Labels leaving relocation information referencing the wrong hunk has been corrected. 4) Problems stopping the program on disk write errors, particularly disk full have been eliminated. 5) ENTRY Labels declared but undefined no longer are made visible to the linker (they formerly appeared referencing the base of the first hunk.) Version 1.2.1 Beta1..........released 13-Aug-87 1) Symbols containing periods are now handled correctly within mnemonic expressions. A special note of gratitude to various members of ASDF (Amiga Software Developers Forum), The Software Distillery (whose BLink reduced the many hours spent relinking the source files during development), and especially John Toebes, whose offhand remarks unknowingly provided much of the inspiration to keep going. Also DJ JAMES, KEN S and cheath for their work in running down some of the problems I missed. NOTE: Amiga and AmigaDOS are trademarks of Commodore Business Machines. Intel is a trademark of the Intel Co. MC68000 and MC68010 are trademarks of Motorola Co. THE END